eCall Development Server - Remote API

Success

4.4. POST /phones/savePhone

Modify a phone by including the ID of an existing phone. Save a new phone by omitting the phone ID or setting it to 0. The phone mode (IVS or PSAP) is restricted by the rights of the usergroup the current user is in. Violations will be overwritten with the allowed mode, i.e. if a user tries to create an IVS phone while his usergroup is only allowed to create PSAPs, the resulting phone will be created with mode PSAP. The phone number can only be changed if there are no calls associated with this phone.

Parameter

Type

Remarks

Phone

Must be included in JSON format in request body

Responses:

Code

Body

Description

200

Success

4.5. POST /phones/deletePhone

Delete an existing phone. A phone can only be deleted when it is not associated with any calls, sms or tcp connections.

Parameter

Type

Remarks

phoneId

Number

Responses:

Code

Body

Description

200

Success

4.6. POST /phones/assignTestCase

Assign a test case to a phone.

Parameter

Type

Remarks

phoneId

Number

testCaseId

Number

Responses:

Code

Body

Description

200

Success

4.7. POST /phones/assignTestCaseGroup

Assign a test case group to a phone.

Parameter

Type

Remarks

phoneId

Number

testCaseGroupId

Number

Responses:

Code

Body

Description

200

Success

4.8. GET /calls

List all calls.

Parameter

Type

Remarks

phoneId

Number

Optional. Results will only contain calls from or to this phone.

sortDir

String

Optional. Use "asc" or "desc" for ascending or descending order of results. Default is "asc".

max

Number

Optional. Limits the maximum number of results.

fromTime

DateTime

Optional. Restrict results to calls made at or after this time. Time zone must be specified.
Examples:
2024-01-01T00:00:00Z
2024-01-01T02:00:00+02:00

toTime

DateTime

Optional. Restricts results to calls made at or before this time. Time zone must be specified.
Examples:
2024-12-31T23:59:59Z
2024-12-31T21:59:59-02:00

Responses:

Code

Body

Description

200

Array<PhoneCall>

Success

4.9. GET /calls?callId={callId}

Retrieve a specific call.

Parameter

Type

Remarks

callId

Number

Responses:

Code

Body

Description

200

PhoneCall

Success

4.10. GET /calls/downloadAudio?callId={callId}

Retrieve audio recordings for a specific call.

Parameter

Type

Remarks

callId

Number

Responses:

Code

Body

Description

200

Zip file

The zip file will contain two wav files, one file name ending in out.wav and one ending in in.wav. For incoming calls in.wav contains the external audio channel and out.wav contains the internal audio channel. For outgoing calls the order is reversed.

4.11. POST /calls/makeCall

Make a call to a phone or phone number. If a phone number is given and a phone with that phone number does not exist, the phone will automatically be generated and the user group’s default test case will be assigned. The generated phone’s mode will be IVS if the user group’s mode is set to PSAP simulation exclusively, otherwise it will be PSAP.

If a test case ID is given then the corresponding test case will only be used for this one call. If no test case ID is given then the phone’s assigned test case will be used for the call.

Returns the call ID of the call that was initiated.

Parameter

Type

Remarks

phoneId

Number

Mandatory if phoneNumber is not given

phoneNumber

String

Mandatory if phoneId is not given

testCaseId

Number

Optional.

Responses:

Code

Body

Description

200

Success

4.12. POST /calls/hangUp

Hang up a call.

Parameter

Type

Remarks

callId

Number

Responses:

Code

Body

Description

200

Success

4.13. POST /calls/dropCall

Drops a call without sending a SIP BYE.

Parameter

Type

Remarks

callId

Number

Responses:

Code

Body

Description

200

Success

4.14. POST /calls/inbandRequestMsd

Request an inband MSD transmission. The call must be active.

Parameter

Type

Remarks

callId

Number

alAckValue

Number

Optional. Allowed range is between 0 and 15. Set this to 2 to send an AL clear down.

Responses:

Code

Body

Description

200

Success

4.15. POST /calls/ngRequestMsd

Request a next generation MSD transmission by sending a SIP INFO request. The call must be active.

Parameter

Type

Remarks

callId

Number

Responses:

Code

Body

Description

200

Success

4.16. GET /sms

List all/some SMS. An array of SMS is returned. If the SMS body contains a valid MSD, it is decoded including it’s OSD and stored with the SMS.

Parameter

Type

Remarks

sortDir

String

Optional. Use "asc" or "desc" for ascending or descending order of results.

max

Number

Optional. Limits the maximum number of results.

Responses:

Code

Body

Description

200

Array<Sms>

Success

4.17. GET /sms?smsId={smsId}

Retrieve a specific sms.

Parameter

Type

Remarks

smsId

Number

Responses:

Code

Body

Description

200

Success

4.18. POST /sms/requestCall

Request a callback from IVS via SMS. Returns the id of the SMS just sent or an error message.

Parameter

Type

Remarks

ivsPhoneId

String

activation

String

Set to either MANUAL or AUTOMATIC

Responses:

Code

Body

Description

200

Success

4.19. POST /sms/requestMsd

Request a MSD from IVS via SMS. Returns the id of the SMS just sent or an error message.

Parameter

Type

Remarks

ivsPhoneId

String

mid

Number

Number between 0 and 255

transport

String

One of “any”, “sms”, “tcp/ip”, “voice”

Responses:

Code

Body

Description

200

Success

4.20. POST /sms/requestAccel

Request acceleration info from IVS via SMS. Returns the id of the SMS just sent or an error message.

Parameter

Type

Remarks

ivsPhoneId

String

Responses:

Code

Body

Description

200

Success

4.21. POST /sms/requestTrack

Request track info from IVS via SMS. Returns the id of the SMS just sent or an error message.

Parameter

Type

Remarks

ivsPhoneId

String

Responses:

Code

Body

Description

200

Success

4.22. POST /sms/requestConfig

Request or set configuration parameters from/in the IVS via SMS. Returns the id of the SMS just sent or an error message.

Parameter

Type

Remarks

ivsPhoneId

String

actionCode

String

Either “get” or “set”

parameter

String

One of the parameter names found in the GUI, i.e. EGTS_SIM_PIN

parameterValue

String

The value to set the given parameter to. Will be ignored (and can be omitted) for “get” action.

Responses:

Code

Body

Description

200

Success

4.23. POST /sms/requestTestMode

Request to switch testmode on or off in IVS via SMS. Returns the id of the SMS just sent or an error message.

Parameter

Type

Remarks

ivsPhoneId

String

mode

String

Set to either “start” or “stop”

Responses:

Code

Body

Description

200

Success

4.24. POST /sms/requestDeregistration

Request deregistration of IVS via SMS. Returns the id of the SMS just sent or an error message.

Parameter

Type

Remarks

ivsPhoneId

String

Responses:

Code

Body

Description

200

Success

4.25. GET /tests

List all test cases and / or test case groups.

Parameter

Type

Remarks

onlyTestCases

Boolean

If true, only include test cases in the response. Default: false

onlyTestCaseGroups

Boolean

If true, only include test case groups in the response. Default: false

Responses:

Code

Body

Description

200

Array<TestCase|TestCaseGroup>

Success

4.26. GET /tests?testCaseId={testCaseId}

List a specific test case.

Parameter

Type

Remarks

testCaseId

Number

Responses:

Code

Body

Description

200

TestCase

Success

4.27. GET /tests?testCaseGroupId={testCaseGroupId}

List a specific test case.

Parameter

Type

Remarks

testCaseGroupId

Number

Responses:

Code

Body

Description

200

TestCaseGroup

Success

4.28. POST /tests/saveTestCase

Modify an existing test case by including the ID of an existing test case. Save a new test case by omitting the test case ID. Only valid test parameters can be changed in IVS Test Server mode.

Parameter

Type

Remarks

TestCase

Must be included in JSON format in request body

Responses:

Code

Body

Description

200

TestCase

Success

4.29. POST /tests/deleteTestCase

Delete an existing test case. A test case can only be deleted when it is not assigned to any phones and it can’t be the default test case of a user group.

Parameter

Type

Remarks

testCaseId

Number

Responses:

Code

Body

Description

200

Success

4.30. POST /tests/saveTestCaseGroup

Modify an existing test case group by including the ID of an existing test case group. Save a new test case group by omitting the test case group ID.

Parameter

Type

Remarks

TestCaseGroup

Must be included in JSON format in request body

Responses:

Code

Body

Description

200

TestCaseGroup

Success

4.31. POST /tests/deleteTestCaseGroup

Delete an existing test case group. A test case group can only be deleted when it is not assigned to any phones.

Parameter

Type

Remarks

testCaseGroupId

Number

Responses:

Code

Body

Description

200

Success

4.32. GET /conformance/listTests

List all available conformance tests.

Parameter

Type

Remarks

No parameters

Responses:

Code

Body

Description

200

ConformanceTests

Success

4.33. POST /conformance/startTest

Start a conformance test.

Parameter

Type

Remarks

StartTestArguments

Responses:

Code

Body

Description

200

{"conformanceTestId": <Number>}

Response body contains the ID of the conformance test that was just started.

4.34. POST /conformance/cancelTest

Cancel a running conformance test.

Parameter

Type

Remarks

conformanceTestId

Number

Responses:

Code

Body

Description

200

Success

4.35. POST /conformance/userPromptResult

Transmit a user response to a question or request.

Parameter

Type

Remarks

conformanceTestId

Number

yes

Boolean

True if user’s response was positive, else false.

4.36. GET /conformance/listResults

List conformance test results.

Parameter

Type

Remarks

phoneId

Number

Optional. Results will only contain test results where this phone was the system under test.

sortDir

String

Optional. Use "asc" or "desc" for ascending or descending order of results. Default is "asc".

max

Number

Optional. Limits the maximum number of results. Default is unlimited.

includeLogs

Boolean

Optional. Include logs for all test results. Default is unlimited.

Responses:

Code

Body

Description

200

Array<ConformanceTestResult>

Success

4.37. GET /conformance/result

Retrieve result of a single test.

Parameter

Type

Remarks

conformanceTestId

Number

ID of the conformance test.

Responses:

Code

Body

Description

200

ConformanceTestResult

Success

5. WebSocket Interface

The WebSocket interface uses STOMP version 1.2. STOMP is a publish/subscribe type of protocol which allows clients to only receive messages that they are interested in by subscribing to certain topics. See http://jmesnil.net/stomp-websocket/doc/ for further information and available client libraries.

The endpoint to connect to: ws(s)://<host>/api/v1

The WebSocket interface allows the ES to receive events from the ECDS without delay as they are happening.

5.1. Authentication

The CONNECT message must include a login and passcode header containing the user’s user name and password.

5.2. Subscriptions

All messages sent by the server are being sent to destinations of the following format: /calls/$externalSubscriberMode/$messageType/$externalSubscriberPhoneNumber.

To receive incoming SMS, the destination starts with sms: /sms/$externalSubscriberMode/event/$externalSubscriberPhoneNumber

The destination part $externalSubscriberMode is either ivs, if external subscriber is an IVS or psap, if external subscriber is a PSAP.

The destination part $messageType is one of: state, log, or event. If the message type is state, then the message body will contain a message of type CallState. If the message type is log, then the message body will contain a message of type CallLogs. If the message type is event, then the message body will be of type CallEventMsdReceived or CallEventMsdSent. The SMS destination knows only one messageType event. All messages to this destination are of type CallEventSmsReceived. See chapter 5 for a description of these JSON models.

The destination part $externalSubscriberPhoneNumber is the phone number of the external subscriber.

Ant style wildcard patterns (https://ant.apache.org/manual/dirtasks.html) are allowed when subscribing to a destination.

Examples of subscriptions:

Destination

Description

/calls/**

The client subscribes to all messages from the server. Note that the user’s role might restrict him to receive messages for which he doesn’t own the permission, e.g. calls that belong to a different user group.

/calls/ivs/**

The client will receive all messages where the external subscriber is an IVS.

/calls/psap/**

The client will receive all messages where the external subscriber is a PSAP.

/calls/*/state/*

The client will receive all CallState messages from IVS and PSAPs.

/calls/*/*/+491234567890

The client will receive all messages that belong to calls from/to external subscriber with phone number +491234567890.

/sms/*/event/*

The client will receive all incoming SMS, from any phone in any mode.

All messages will be sent as soon as the corresponding event occurs. To receive information on recent calls send a message with empty body to destination /app/api/calls, e.g. directly after the connection has been established and the subscriptions have been made.

For conformance tests only one subscription is needed: /conformance/**.

This subscription will receive messages of types:

ConformanceTestUserPrompt
ConformanceTestState
ConformanceTestLog

Messages of types ConformanceTestState and ConformanceTestLog inform the consumer about the state of a running conformance test. A message of type ConformanceTestUserPrompt requests information from the user which needs to be transmitted back to ECDS through the /conformance/userPromptResult REST call.

6. JSON Models

Types ending with a question mark may be null. Dates are represented as ISO-8601strings with millisecond resolution and time zone, e.g. "1970-01-01T23:59:59.999Z".

6.1. Version

Member

Type

Description

applicationVersion

String

e.g. "3.7.0"

remoteApiVersion

String

e.g. "1.7"

coreVersion

String

e.g. "4.0"

6.2. CallEventMsdReceived

Member

Type

Description

type

String

"event"

eventType

String

"msdReceived"

msd

Msd

6.3. CallEventMsdSent

Member

Type

Description

type

String

"event"

eventType

String

"msdSent"

msd

Msd

6.4. CallEventSmsReceived

Member

Type

Description

type

String

"event"

eventType

String

"smsReceived"

sms

6.5. CallLog

Member

Type

Description

time

Date

Time of log message.

level

String

Level of log message.

text

String

Text of log message.

6.6. CallLogs

Member

Type

Description

type

String

"logs"

messages

Array<CallLog>

6.7. CallState

Member

Type

Description

type

String

"state"

callId

Number

ID of the call.

callBegin

Date

Begin of the call.

callEnd

Date?

End of call or null if call is still in progress.

internalCallState

String

SETUP, ACTIVE, ENDED

externalCallState

String

SETUP, MSD_TRANSMISSION, ACTIVE, ENDING, ENDED

msdTransmissionState

String

WAITING, START_RECEIVED, NACK_RECEIVED, LL_ACK_RECEIVED, AL_ACK_RECEIVED, SEND_RECEIVED, MSD_RECEIVED, NACK_SENT, LL_ACK_SENT, AL_ACK_SENT

internalSubscriber

String

Phone number of internal subscriber.

externalSubscriber

String

Phone number of external subscriber.

externalSubscriberMode

String

Either "psap" or "ivs".

externalSubscriberTag

String

Tag of phone of external subscriber.

calledSubscriber

String

The called phone number of an incoming call. Empty if outgoing call.

incoming

Boolean

True if incoming call, false if outgoing call.

6.8. Phone

Member

Type

Description

phoneId

Number

ID of the phone.

phoneNumber

String

Phone number of the phone.

description

String

Description of the phone.

email1

String

Email 1

email1Active

Boolean

email2

String

Email 2

email2Active

Boolean

testCaseId

Number

ID of assigned test case.

testCaseGroupId

Number?

ID of assigned test case group. Null, if no test case group is assigned to phone.

egTerminalIdentifier

Number?

ERA-GLONASS terminal identifier, may be null.

mode

String

"ivs", if this phone represents an IVS, "psap", if this phone represents a PSAP.

tag

String

User defined tag.

allowOutgoingCalls

Boolean

Phone is allowed to make outgoing calls.

6.9. PhoneCall

Member

Type

Description

callId

Number

ID of the call.

begin

Date

Begin of the call.

end

Date?

End of the call. Null, if call is in progress.

incoming

Boolean

True, if call is incoming. False, if call is outgoing.

internalSubscriber

String?

Phone number of the internal subscriber. Null, as long as connection to internal subscriber has not been made.

externalSubscriber

Phone record of the external subscriber.

calledSubscriber

String?

The called number. Only for incoming calls and when information is known.

dataSets

Array<Msd>

Received or sent MSDs.

logMessages

Array<CallLog>

Chronologically sorted log messages belonging to the call.

6.10. Sms

Member

Type

Description

smsId

Number

ID of the SMS.

phone

Associated phone.

otherPhone

String?

timestamp

Number

Unix timestamp of when the SMS was sent.

deliveryTimestamp

Number?

Unix timestamp of when the SMS was delivered. Only when information is known.

incoming

Boolean

True, if SMS is incoming. False, if SMS is outgoing.

externalMessageRef

String

External message reference if known. Empty String if unknown.

type

String

Content type of SMS body, either “text” or “binary”.

body

String

SMS body.

udh

String

status

String

Either "accepted", "delivered" or "error".

errorStatus

String

Error status.

parts

Array<Sms>?

Array holding the parts of a multipart message.

concatSms

Sms?

Reference of the concatenated SMS.

concatRef

Number?

Reference id of concatenated SMS.

concatPart

Number?

Part number for concatenated SMS.

concatTotal

Number?

Total number of parts for concatenated SMS.

dataSets

Msd?

If SMS body contains a valid MSD, it is decoded and stored here, including its OSD.

6.11. TestCase

Member

Type

Description

testCaseId

Number

ID of the test case.

name

String

Name of the test case.

description

String

Description of the test case.

mode

String

"ivs", if this test case represents an IVS test case, "psap", if this test case represents a PSAP test case.

testParameters

TestParametersIvs

TestParametersPsap

6.12. TestParameters

This type is the parent type of TestParametersIvs and TestParametersPsap and contains parameters that are common to both test case modes.

Member

Type

Description

acceptCall

Boolean

rejectCallMode

Number

Allowed values: 480, 486, 500, 503, 603, -1. The values are the SIP response code of the final response to the incoming INVITE, except -1 which means no final response will be sent.

ringingDuration

Number

In seconds, 0 to disable ringing

callAnswerMode

String

AUTOMATIC, MANUAL

callerId

String

callSetup

String

ASAP, MODEM_CONTROLLED

hangUpCallAfter

Number

In seconds, 0 to disable.

internalSubscriber

String

ngEcall

Boolean

recordAudio

Boolean

simulateCrcError

Boolean

useInbandModem

Boolean

6.13. TestParametersIvs

This type inherits all members from TestParameters.

Member

Type

Description

alAckHandling

String

fixed, auto

alAckValue

Number

0..15

hangUpCallOn

String

NEVER, CALL_ESTABLISHED, INBAND_SEND_SIGNAL_RECEIVED, INBAND_MSD_RECEIVED, INBAND_NACK_SENT, INBAND_LL_ACK_SENT, INBAND_AL_ACK_SENT

ignoreSendSignal

Boolean

inbandDirection

String

PUSH, PULL

ngAckValue

String

auto, true, false, none

numberOfAlAcks

Number

numberOfLlAcks

Number

sendNecDisabler

Boolean

t4Timer

Number

In seconds.

t8Timer

Number

In seconds.

numberOfMsdReqs

Number

pauseBetweenMsdReqs

Number

In seconds.

automaticCallback

Boolean

secondsBeforeAutomaticCallback

Number

In seconds.

6.14. TestParametersPsap

This type inherits all members from TestParameters.

Member

Type

Description

msd

Array<Msd>

msdAutoSetMsgId

Boolean

msdAutoSetTimestamp

Boolean

ngUrn

String

Empty string to disable.

ngSendDataResponse

String

Allowed values: damaged, unsupported, data-unsupported, security-failure, unable or empty string to enable standard-compliant behavior.

t5Timer

Number

In seconds.

t6Timer

Number

In seconds.

t7Timer

Number

In seconds.

6.15. TestCaseGroup

Member

Type

Description

testCaseGroupId

Number

ID of the test case group.

name

String

Name of the test case group.

description

String

Description of the test case group.

mode

String

"ivs", if this test case represents an IVS test case group,
"psap", if this test case represents a PSAP test case group.

testCases

Array<Number>

The IDs of the test cases that are assigned to this group.

6.16. Msd

When used as test parameter input then only one of raw or decoded should be set and all other fields should be omitted. The field msdType is only exists when this is being used in msdReceived event of WebSocket interface.

Member

Type

Description

decoded

MsdDecoded?

Decoded fields of MSD. May be null, if MSD could not be decoded.

errors

Array<String>

Errors that were encountered during decoding. Empty, if no errors occurred during decoding.

msdType

String

"ng" or "inband"

raw

String

Hex string encoding of 140 bytes MSD (280 characters)

6.17. MsdDecoded

Member

Type

Description

activation

String

AUTOMATIC, MANUAL

callType

String

EMERGENCY, TESTCALL

compressedNaturalGas

Boolean

dieselTank

Boolean

electricEnergyStorage

Boolean

eventTime

Date

formatVersion

Number

0..255

gasolineTank

Boolean

hydrogenStorage

Boolean

liquidPropaneGas

Boolean

messageId

Number

0..255

numberOfPassengers

Number?

0..255

optionalAdditionalDataDecoded

Object?

Only if OID is known and no errors occurred during decoding.

optionalAdditionalDataOid

String

String representation of OID, e.g. "1.4.2"

optionalAdditionalDataRaw

String

Hex string encoding

otherStorage

Boolean

positionConfidence

String

CAN_BE_TRUSTED, LOW_CONFIDENCE

positions

Array<Position>

Usually between 0 and 3 positions but can contain more if additional positions could be decoded from optional set of data.

vehicleDirection

Number?

0..359

vehicleType

String

EXTENDED, PASSENGER_VEHICLE_M1, BUSES_AND_COACHES_M2, BUSES_AND_COACHES_M3, LIGHT_COMMERCIAL_VEHICLES_N1, HEAVY_DUTY_VEHICLES_N2, HEAVY_DUTY_VEHICLES_N3, MOTORCYCLES_L1E, MOTORCYCLES_L2E, MOTORCYCLES_L3E, MOTORCYCLES_L4E, MOTORCYCLES_L5E, MOTORCYCLES_L6E, MOTORCYCLES_L7E

vin

String

17 character vehicle identification number

6.18. ConformanceTests

Member

Type

Description

ngPsapTests

EN17240 conformance tests for PSAP.

ngIvsTests

EN17240 conformance tests for IVS.

ibPsapTests

EN16454 conformance tests for PSAP.

ibIvsTests